Kotlin Multiplatform Client for Docker/dev.limebeck.libs.docker.client/DockerClient

DockerClient

open class DockerClient(val config: DockerClientConfig = DockerClientConfig()) : ApiCacheHolder, AutoCloseable

Client for one Docker host, using fixed API version 1.51 and a Unix socket.

Reuse an instance for application-scoped work, or use Kotlin use for a short-lived client. close shuts down the owned HTTP client; raw exec/attach sessions must be closed separately. No API negotiation, Docker context discovery or automatic retry/reconnect is performed.

Import dev.limebeck.libs.docker.client.api.* to access containers, images, exec and other API groups.

Parameters

config

Serialization, endpoint and in-memory registry authentication settings.

Samples

DockerClient(DockerClientConfig(
    connectionConfig = DockerClientConfig.ConnectionConfig.SocketConnection(socketPath),
)).use { docker ->
    docker.system.ping().getOrThrow()
    docker.containers.getList().getOrThrow().forEach { println(it.names) }
}

Constructors

DockerClient

constructor(config: DockerClientConfig = DockerClientConfig())

Types

Companion

object Companion

Properties

apiCache

open override val apiCache: MutableMap<Any, Any>

client

val client: HttpClient

Owned Ktor HTTP client. Prefer close or use for lifecycle management. Changing its configuration can affect all API groups sharing this client.

compose

val DockerClient.compose: Compose

Cached Compose integration using this client's endpoint and lifetime.

config

val config: DockerClientConfig

containers

val DockerClient.containers: Containers

Cached containers API bound to this client and its connection configuration.

exec

val DockerClient.exec: Exec

Cached exec API bound to this client and its connection configuration.

images

val DockerClient.images: Images

Cached images API bound to this client and its connection configuration.

json

val json: Json

networks

val DockerClient.networks: Networks

Cached networks API bound to this client and its connection configuration.

swarm

val DockerClient.swarm: Swarm

Cached Swarm API using this client's endpoint and lifetime.

system

val DockerClient.system: System

Cached system API bound to this client and its connection configuration.

volumes

val DockerClient.volumes: Volumes

Cached volumes API bound to this client and its connection configuration.

Functions

apiPath

fun apiPath(path: String): String

Builds the path shared by HTTP and raw hijack requests.

applyAuthForRegistry

fun HttpRequestBuilder.applyAuthForRegistry(registry: String)

applyConnectionConfig

fun HttpRequestBuilder.applyConnectionConfig()

applyStreamConfig

fun HttpRequestBuilder.applyStreamConfig()

Live streams may be idle indefinitely; the collector owns their lifetime.

auth

suspend fun DockerClient.auth(authConfig: AuthConfig): Result<SystemAuthResponse, ErrorResponse>

Validates registry credentials through Docker and stores successful authentication in DockerClientConfig.auth.

open override fun close()

Closes the owned HTTP client. Repeated calls are safe. Stop collectors and close independently owned exec/attach sessions before shutdown. This method initiates shutdown without waiting for active HTTP calls to finish.

consumeStream

suspend fun <T> HttpResponse.consumeStream(block: suspend (ByteReadChannel) -> T): T

Validate transport completion as well as status; CIO can report a short body as clean EOF.

createInteractiveSession

suspend fun DockerClient.createInteractiveSession(tty: Boolean, method: HttpMethod, path: String, parameters: Parameters = Parameters.Empty, headers: Map<String, String> = emptyMap(), body: ByteArray? = null): Result<ExecSession, ErrorResponse>

diagnoseConnection

suspend fun DockerClient.diagnoseConnection(timeoutMillis: Long): ConnectionDiagnostic

Probes the configured daemon using the SDK's versioned ping without changing daemon state. A successful probe establishes reachability/API acceptance, not permission for every Docker operation. Does not retry or close this client. Cancellation from the caller always propagates.

diagnoseFailure

fun DockerClient.diagnoseFailure(failure: Throwable): ConnectionDiagnostic

Describes an upstream transport exception without retrying or modifying it. Use for failures from HTTP calls, stream collection or exec/attach. Do not use to label application callback errors. Recognizes common exception names and OS messages/codes; unsupported/localized messages remain UNKNOWN. Cancellation is rethrown. Clean stream EOF has no exception and requires application-owned reconciliation.

errorResponse

suspend fun HttpResponse.errorResponse(): ErrorResponse

Handles bodyless HEAD errors and non-JSON daemon/proxy responses.

errorResult

suspend fun HttpResponse.errorResult(): Result<Nothing, ErrorResponse>

An HTTP error Result retaining safe request context for getOrThrow.

openRawConnection

suspend fun openRawConnection(): DockerRawConnection

parse

inline suspend fun <T> HttpResponse.parse(): Result<T, ErrorResponse>

requireStreamSuccess

suspend fun HttpResponse.requireStreamSuccess()

Cold streams surface HTTP failures during collection, before decoding data.

validateImageProgress

suspend fun HttpResponse.validateImageProgress(): Result<Unit, ErrorResponse>

Docker can report an operation failure inside a successful NDJSON response.

suspend fun <TAux> HttpResponse.validateImageProgress(auxSerializer: KSerializer<TAux>, onProgress: suspend (ImageProgress<TAux>) -> Unit): Result<Unit, ErrorResponse>

validateOnly

inline suspend fun HttpResponse.validateOnly(): Result<Unit, ErrorResponse>

DockerClient

Parameters

See also

Samples

Constructors

Types

Properties

Functions